home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v2.1 / Amiga Developer CD v2.1.iso / Contributions / Haage_&_Partner / Storm-Projects / NDKExamples1 / locale / Localize / localize.doc < prev    next >
Text File  |  1999-04-16  |  13KB  |  452 lines
  1.                    
  2.  
  3.  
  4.  
  5.  
  6.                    LOCALIZE
  7.  
  8.  
  9.  
  10.     Format:        LOCALIZE {<name|pattern>
  11.             LOCALIZE PATCH [DIR|DIRECTORY <name>]
  12.                  [MC|MERGECATALOG <file>] [SORT]
  13.                  [MIN|MINIMUM <number>] [NEST]
  14.                  [EXF|EXCEPTFUNCS <file>]
  15.                  [EXS|EXCEPTSTRINGS <file>]
  16.                  [FUNC|FUNCTION <name>] [TEMP|TEMPLATE <text>]
  17.                  [PS|PREPENDSTRING <text>] [PF|PREPENDFILE <file>]
  18.                  [AS|APPENDSTRING <text>] [AF|APPENDFILE <file>]
  19.                  [SH|SILENT] {FILES}  
  20.  
  21.     Template:   PATCH/S,DIR=DIRECTORY/K,MC=MERGECATALOG/K,SORT/S,
  22.             MIN=MINIMUM/K/N,NEST/S,
  23.             EXF=EXCEPTFUNCS/K,EXS=EXCEPTSTRINGS/K
  24.             FUNC=FUNCTION/K,TEMP=TEMPLATE/K,
  25.             PS=PREPENDSTRING/K,PF=PREPENDFILE/K,
  26.             AS=APPENDSTRING/K,AF=APPENDFILE/K,
  27.             SH=SILENT/S,FILES/A/M
  28.  
  29.     Purpose:    To localize C source files.
  30.  
  31.     Specification:
  32.  
  33.     (Changed lines are denoted by a vertical bar in the left margin.)
  34.  
  35.     LOCALIZE has two distinct operation modes:  parsing and
  36.     patching.  You select the mode by supplying or omitting the
  37.     PATCH keyword.
  38.  
  39.     If the PATCH keyword is not given, LOCALIZE reads each file
  40.     specified (or matched by a wildcard) and writes a record to
  41.     the output for each string found.  Typically, you will
  42.     redirect the output to a file for editing.
  43.  
  44.     The format of the output records is as follows:
  45.  
  46.       file|type|line|start column|end column|message tag|string
  47.  
  48.     <file> is the name of the file where a string was found.
  49.  
  50. |    <type> is a single character that may be 'S' for a localizable
  51. |    string, 'E' for a non-localizable string, or 'D' for a
  52. |    non-localizable string that occurs in a '#define'.  (A string
  53. |    is considered non-localizable when it located outside of a C
  54. |    function.)
  55.  
  56.     <line> is the number of the line in <file> where the string
  57.     was found.
  58.  
  59.     <start column> is column where the opening double quote (")
  60.     appears.  (The line begins with column 1.)
  61.  
  62.     <end column> is column where the closing double quote (")
  63.     appears.
  64.  
  65.  
  66.  
  67.     <message tag> is the name that will be used to refer to the
  68.     string.
  69.  
  70.     <string> is the text that was found.
  71.  
  72.     If LOCALIZE encounters strings that are defined outside of a
  73. |    function it will set <type> to 'E', or 'D' if that string
  74. |    appears as part of a '#define'.  Strings defined outside
  75.     a function  require special handling because there is no
  76.     program context in which to execute a function call.  Strings
  77. |    described by 'D' or 'E' records are not patched in the source,
  78. |    but are added to the catalog description (.cd) file as
  79. |    comments.  A string occurring in a '#define' receives special
  80. |    treatment because it may or may not be localizable.
  81.  
  82. |    A type 'D' string may be localized if, and only if, the macro
  83. |    is used exclusively within functions.  Compiler errors will
  84. |    result if the macro is localized and used outside a function. 
  85.  
  86.     Sometimes localization is undesirable; system assigns (SYS:,
  87.     FONTS:, etc.) or debugging statements (ex: D(bug("oops!")))
  88.     for example.  By using exception files LOCALIZE can be made to
  89.     bypass strings that would otherwise be localized.
  90.  
  91.     This may be done in two ways; by the contents of a string or
  92.     by that name of a calling function.
  93.  
  94.  
  95.     Edit the string record file, deleting entries that should not
  96.     be localized ("S:" for example), and changing the message tags
  97.     if desired.  In particular, if there is a string that appears
  98.     in 10 places there should be 1 message tag that appears in 10
  99.     entries in this file, not 10 message tags each referring to
  100.     the same string.
  101.  
  102.     WARNING:  Do not alter the ordering of the lines in the string
  103.           record file.  The lines are sorted first by line
  104.           number, then by starting column number.  If the
  105.           string records are not sorted the results are
  106.           undefined. 
  107.  
  108.     Run LOCALIZE with the PATCH switch and the edited file string
  109.     record file to create a localized C source file and a Catalog
  110.     Description file (.cd file).  These files will be placed in
  111.     the subdirectory "Localized-Source".
  112.  
  113.     The directory name may be changed by supplying the DIRECTORY
  114.     keyword and a name.  If <name> contains a colon (':') all
  115.     localized source files and catalog descriptions will be saved
  116.     there.  If <name> does not contain a colon, <name> will be
  117.     concatenated with the directory where a file is found to
  118.     produce an output directory for that file.
  119.  
  120.     The default behavior of LOCALIZE is to write a .cd file for
  121.     every source file that is patched.  If a common .cd file is
  122.     desired, the MERGECATALOG keyword should be given with the
  123.     desired name for the catalog description file.
  124.  
  125.  
  126.  
  127.     LOCALIZE will write entries to the .cd file in the order
  128.     encountered; the previous version sorted the entries by the
  129.     message ID.  The old behavor may be obtained by supplying the
  130.     SORT switch, which causes localize to sort the .cd file by
  131.     message IDs.
  132.  
  133.     FUNCTION specifies the name of the function to be called to
  134.     localize a string.  If not supplied, FUNCTION defaults to
  135.     'GetCatalogStr'.
  136.  
  137.     The TEMPLATE keyword is followed by a string the specifies the
  138.     calling conventions for FUNCTION.  The substitutions available
  139.     for the TEMPLATE string are:
  140.  
  141.       %F         The function name given by FUNCTION
  142.       %I         The message tag for the string
  143.       %S         The string tag for the string (produced by
  144.              concatenating _STR to the message tag).
  145.       %D         The default string.
  146.  
  147.     If TEMPLATE is not supplied, the following will be used as the
  148.     default:
  149.  
  150.       "(catalog ? %F(catalog, %I, %S) : %S)"
  151.  
  152.     Assuming the default for FUNCTION, the following string
  153.     record:
  154.  
  155.       demo.c|S|3|11|26|MSG_HELLO|hello world\n
  156.  
  157.     will produce this function call:
  158.  
  159.       (catalog ? GetCatalogStr(catalog, MSG_HI, MSG_HI_STR)
  160.       : MSG_HI_STR)
  161.  
  162.     (The call generated is shown on two lines for clarity.  In
  163.     actuality, the function call is all on one line.)
  164.  
  165.     The SILENT keyword suppresses the progress indicators when
  166.     LOCALIZE is running in patch mode.
  167.  
  168. |    The NEST keyword enables support of nested comments.
  169.  
  170.     PREPENDFILE (APPENDFILE) specifies a file to be prepended
  171.     (appended) the the generated C source file.  PREPENDSTRING
  172.     (APPENDSTRING) provides similar functionality, but the argment
  173.     is taken as a string rather than a file.
  174.  
  175.     NOTE:  If the PATCH switch is omitted, all other switches and
  176.            keywords are silently ignored.
  177.  
  178.  
  179.  
  180.  
  181.     Examples:
  182.  
  183.     These examples will be operating on this source file (line numbers
  184.     added for clarity):
  185.  
  186.  
  187.       1:main()
  188.       2:{
  189.       3:    printf("hello world\n");
  190.       4:}
  191.  
  192.  
  193.     LOCALIZE operating in parse mode generates one line of output
  194.  
  195.  
  196.       1>LOCALIZE hello.c
  197.       hello.c|S|3|11|26|MSG_0000|hello world\n
  198.  
  199.  
  200.     Usually, you will redirect this output to a file like this:
  201.  
  202.  
  203.       1>LOCALIZE >RAM:strings hello.c
  204.  
  205.  
  206.     LOCALIZE operating in patch mode:
  207.  
  208.  
  209.       1>LOCALIZE PATCH RAM:strings
  210.       Processing RAM:strings...
  211.         hello.c -> hello.c.new & hello.c.cd
  212.         patching line 3
  213.         hello.c done.
  214.       RAM:strings done.
  215.  
  216.  
  217.     This is the C source file produced by LOCALIZE:
  218.  
  219.  
  220.       1: /*
  221. |      2: **    This file generated by localize 2.9 (AmigaDOS 2.1) from hello.c
  222.       3: */
  223.       4: main()
  224.       5: {
  225.       6:     printf((catalog?GetCatalogStr(catalog,MSG_0000,MSG_0000_STR)
  226.             :"hello world\n"));
  227.       7: }
  228.  
  229.  
  230.     And this is the Catalog Description file:
  231.  
  232.  
  233.       1: ;
  234. |      2: ;    Description generated by localize 2.9 (AmigaDOS 2.1) from hello.c
  235.       3: ;
  236.       4: ; line 3
  237.       5: ;
  238.       6: MSG_0000 (//)
  239.       7: hello world\n
  240.  
  241.  
  242.  
  243.     If you find that the C source becomes too unreadable, you may wish
  244.     to try the following, to use a macro to hide some of the work:
  245.  
  246.  
  247.       1>LOCALIZE PATCH TEMPLATE "_S(%I,%S,%D)"
  248.         PS "#define _S(x,y,z)) catalog?GetCatalogStr(catalog,x,y) ? z)"
  249.         RAM:strings
  250.  
  251.       Processing RAM:strings...
  252.         hello.c -> hello.c.new & hello.c.cd
  253.         Prepending "#define _S(x) catalog?GetCatalogStr(catalog,x,y) ? z)"
  254.         patching line 3
  255.         hello.c done.
  256.       RAM:strings done.
  257.  
  258.  
  259.     This is the C source file produced:
  260.  
  261.  
  262.       1: /*
  263. |      2: **    This file generated by localize 2.9 (AmigaDOS 2.1) from hello.c
  264.       3: */
  265.       4:#define _S(x) catalog?GetCatalogStr(catalog,x,y) ? z)
  266.       5: main()
  267.       6: {
  268.       7:     printf(_S(MSG_0000,MSG_0000_STR,"hello world\n"));
  269.       8: }
  270.  
  271.  
  272.     One thing that LOCALIZE does not attempt to support is strings
  273.     that have a global scope.  That is, any string that is not
  274.     part of a function.  For example:
  275.  
  276.     
  277.        1:char    *help[] =
  278.        2:{
  279.        3:    "Usage: hello <name>",
  280.        4:    "\tPrint a message saying hello to <name>",
  281.        5:    "\tIf <name> is omitted, it defaults to \"world\".",
  282.        6:    0
  283.        7:};
  284.        8:
  285.        9:main ( int argc, char * argv [] )
  286.       10:{
  287.       11:    int    i;
  288.       12:
  289.       13:    if (argc > 2)
  290.       14:        for (i = 0; help[i]; i++)
  291.       15:           printf(help[i]);
  292.       16:   else
  293.       17:       if (argc == 2)
  294.       18:            printf("Hello %s!\n", argv[1]);
  295.       19:        else
  296.       20:            printf("Hello world\n");
  297.       21:}
  298.  
  299.  
  300.     LOCALIZE will issue 'E' records for the strings on lines 3
  301.     through 5 because they occur outside of a function.  There are
  302.     two approachs to resolving these excluded lines.  Both
  303.     approachs are valid and the choice is a function of the
  304.     organization of the data structures and individual preference.
  305.  
  306.  
  307.  
  308.     In this example, the strings are initialized at run time by a
  309.     call to the function initialize:
  310.  
  311.  
  312.        1:char    *help[4];
  313.        2:
  314.        3:main ( int argc, char * argv [] )
  315.        4:{
  316.        5:    int    i;
  317.        6:
  318.        7:    initialize_strings();
  319.        8:
  320.        9:    if (argc > 2)
  321.       10:        for (i = 0; help[i]; i++)
  322.       11:           printf(help[i]);
  323.       12:   else
  324.       13:       if (argc == 2)
  325.       14:            printf("Hello %s!\n", argv[1]);
  326.       15:        else
  327.       16:            printf("Hello world\n");
  328.       17:}
  329.       18:
  330.       19:void initialize_strings ( void )
  331.       20:{
  332.       21:    help[0] = "Usage: hello <name>";
  333.       22:     help[1] = "\tPrint a message saying hello to <name>";
  334.       23:     help[2] = "\tIf <name> is omitted, it defaults to \"world\".";
  335.       24:     help[3] = 0;
  336.       25:}
  337.  
  338.  
  339.     With the string initialization in a function, LOCALIZE can
  340.     generate code that will correctly retrieve the localized
  341.     strings at runtime. 
  342.  
  343.     The other scheme is a little more involved, but is well suited
  344.     for repetitive structures and large arrays.  
  345.  
  346.     After patching the source file shown above, the resulting
  347.     initialize_strings() function:
  348.  
  349.  
  350.       22:void initialize_strings ( void )
  351.       23:{
  352.       24:    help[0] = catalog
  353.                ? GetCatalogStr(catalog, MSG_0000, MSG_0000_STR)
  354.                : MSG_0000_STR;
  355.       25:    help[1] = catalog
  356.                ? GetCatalogStr(catalog, MSG_0001, MSG_0001_STR)
  357.                : MSG_0001_STR;
  358.       26:    help[2] = catalog
  359.                ? GetCatalogStr(catalog, MSG_0002, MSG_0002_STR)
  360.                : MSG_0002_STR;
  361.       27:     help[3] = 0;
  362.       28:}
  363.  
  364.  
  365.  
  366.     is changed to the following.  The GetString function is
  367.     adapted from the one presented in the 1991 DevCon notes.
  368.  
  369.  
  370.       22:void initialize_strings ( void )
  371.       23:{
  372.       24:    int    i;
  373.       25:
  374.       26:    for (i = MSG_0000; i <= MSG_0002; i++)
  375.       27:        help[i] = GetString(catalog, i);
  376.       28:     help[i] = 0;
  377.       29:}
  378.       30:
  379.       31:STRPTR NotFoundString = "localized string not found";
  380.       32:                                   
  381.           33:STRPTR GetString ( struct Catalog * catalog, ULONG id)
  382.           34:{
  383.           35:    STRPTR local = NotFoundString;
  384.           36:    UWORD  i, last;
  385.           37:
  386.           38:    last = sizeof(AppStrings) / sizeof(AppStrings[0]);
  387.           39:
  388.           40:    for (i = 0; i < last; i++)
  389.           41:    {
  390.           42:        if(AppStrings[i].as_ID == id)
  391.           43:        {
  392.           44:            local = AppStrings[i].as_Str;
  393.           45:            break;
  394.           46:        }
  395.           47:    }
  396.           48:
  397.           49:    if (LocaleBase && catalog && *local)
  398.           50:        local = GetCatalogStr(catalog, id, local);
  399.       51:
  400.           52:    return(local);
  401.           53:}
  402.  
  403.  
  404.     These methods may also be applied to structure initializations:
  405.  
  406.  
  407.          struct TextAttr TOPAZ80 =
  408.          {
  409.              "topaz.font", TOPAZ_EIGHTY, 0, 0
  410.          };
  411.  
  412.  
  413.          struct IntuiText Hello =
  414.          {
  415.              0, 1, JAM2, 10, 10,
  416.              &TextAttr, "Hello World!", NULL
  417.          };
  418.  
  419.  
  420.     Could become the following, allowing LOCALIZE to generate
  421.     function calls to initialize the appropriate structure members
  422.     at run time rather than at compile time.
  423.  
  424.  
  425.  
  426.     NOTE: The string, "topaz.font" is not changed.  The font name
  427.           is not localized and the string record for it must be
  428.           deleted from the string record file.
  429.  
  430.  
  431.          struct TextAttr TOPAZ80 =
  432.          {
  433.              "topaz.font",
  434.              TOPAZ_EIGHTY,
  435.              0, 0
  436.          };
  437.  
  438.          struct IntuiText Hello =
  439.          {
  440.              0, 1,
  441.              JAM2,
  442.              10, 10,
  443.              &TextAttr,
  444.              NULL,
  445.              NULL
  446.          };
  447.  
  448.          initialize_strings()
  449.          {
  450.              Hello.IText = "Hello World!";
  451.          }
  452.